~ chicken-core (chicken-5) /manual/Egg specification format
Trap1[[tags: manual]]2[[toc:]]345== Format of the egg description file67An egg description is basically an association list holding8information about the components of the egg. An egg may contain9multiple components: libraries, programs, Scheme or C include files10and arbitrary data files. Dependencies between eggs can be11specified as can be dependencies between components of an egg.1213A list of valid properties follows.1415=== Global properties1617==== version1819 [egg property] (version STRING)2021Specifies version string for this egg. {{STRING}} should have22the format {{<MAJOR>.<MINOR>.<PATCHLEVEL>}}, where only the23{{<MAJOR>}} part is mandatory.2425Eggs from remote egg servers are automatically versioned - the26version is part of the protocol to retrieve the egg and does not27have to be specified in the {{.egg}} file. Eggs installed from28local directories (see below) should explicitly specify a version.2930==== synopsis3132 [egg property] (synopsis STRING)3334Gives a short description of this egg.3536==== author3738 [egg property] (author STRING)3940Names the author or authors of the contained code.4142==== maintainer4344 [egg property] (maintainer STRING)4546Names the maintainer of this code, if different from author(s).4748==== category4950 [egg property] (category NAME)5152Gives the category under which this egg should be contained.53See [[https://wiki.call-cc.org/chicken-projects/egg-index-5.html|the egg index]]54for a list of currently used categories.5556==== license5758 [egg property] (license STRING)5960Names the license under which this code is available.6162==== dependencies6364 [egg property] (dependencies EGG ...)6566Lists eggs that this egg depends on, and which should be67built and installed if they do not already exist in the repository.68{{EGG}} should be whether a symbol or a list of the form69{{EGGNAME VERSION}}, where the former means to install the70newest available egg with this name and the latter specifies71a specific version or higher.7273This property can also be used to specify a minimum version of CHICKEN74required by the egg. For example, to require at least CHICKEN 5.3.0:7576<enscript highlight=scheme>77(dependencies (chicken "5.3.0"))78</enscript>7980==== test-dependencies8182 [egg property] (test-dependencies EGG ...)8384Lists eggs that are required for this egg to run the tests85(if tests exist.) This only has an effect if the {{-test}}86option has been given to {{chicken-install}}.8788==== build-dependencies8990 [egg property] (build-dependencies EGG ...)9192Lists eggs that are build-time dependencies for this egg,93i.e. there are required to build, but not to run the contained94code. Currently this is treated identical to {{dependencies}}.9596==== foreign-dependencies9798 [egg property] (foreign-dependencies NAME ...)99100Lists external dependencies like native code libraries101or system-specific packages and is currently only used for102documentation purposes.103104==== platform105106 [egg property] (platform PLATFORM)107108Specifies for which platform this egg is intended. {{PLATFORM}}109should be a symbol naming the target platform ({{windows}}, {{linux}}110or {{unix}}) or a boolean combination of platform values, allowed111are {{(not PLATFORM)}}, {{(or PLATFORM ...)}} and {{(and PLATFORM ...)}}.112If the expression can not be satisfied, then installation of this113egg will abort.114115==== distribution-files116117 [egg property] (distribution-files FILE ...)118119List of files required for the installation of the egg. This120form is not handled by chicken-install, but by henrietta-cache to121determine what to cache. If the repository contains additional122files that are unneeded for the egg to be installed, you can list123all the required files in this clause to reduce the amount of data124cached by egg servers.125126==== components127128 [egg property] (components COMPONENT ...)129130Lists components (extensions, programs, include- or data files) that131this extension installs. See [[#component-types|Component types]] and132[[#component-properties|component properties]] for information on how133to specify component-specific information.134135==== host136137 [egg property] (host PROP ...)138139Recursively process {{PROP ...}}, but only for the host (build)140platform, in case this is a "cross-chicken", a CHICKEN installation141intended for cross compilation.142143==== target144145 [egg property] (target PROP ...)146147Recursively process {{PROP ...}}, but only for the target148platform, in case this is a "cross-chicken", a CHICKEN installation149intended for cross compilation.150151==== component-options152153 [egg property] (component-options OPTIONSPEC ...)154155Specifies global options for all programs and extensions compiled for this egg.156{{OPTIONSPEC}} may be {{csc-options}}, {{link-options}} or {{linkage}} specifications.157158==== cond-expand159160 [egg property] (cond-expand CLAUSE ...)161162Conditionally expand egg specification forms, depending on system163features. Each {{CLAUSE}} should be of the form164{{(TEST PROPERTY)}} where {{TEST}} is a feature identifier or a165conditional form, in the same syntax as used in the {{cond-expand}}166syntactic form.167168In addition to normal system-wide feature identifiers, feature identifiers169given via the {{-feature}} option to {{chicken-install}} are visible in170the tests. Also, the features {{target}}, {{host}}, {{dynamic}} and171{{static}} are visible, depending on surrounding egg specification172forms for constraining mode and linkage.173174==== error175176 [egg property] (error STRING ARG ...)177178Signal an error and abort processing. Mostly useful inside {{cond-expand}} forms.179180=== Component types181182==== extension183184 [egg property] (extension NAME PROP ...)185186Specifies an extension library component. The properties187{{PROP...}} are processed recursively and apply only to this188component.189190==== data191192 [egg property] (data NAME PROP ...)193194Specifies one or more arbitrary data files.195196==== generated-source-file197198 [egg property] (generated-source-file NAME PROP ...)199200Specifies a file that is generated during the process of building201the egg.202203==== c-include204205 [egg property] (c-include NAME PROP ...)206207Specifies one or more C include files.208209==== scheme-include210211 [egg property] (scheme-include NAME PROP ...)212213Specifies one or more Scheme include files.214215==== program216217 [egg property] (program NAME PROP ...)218219Specifies an executable program.220221==== c-object222223 [egg property] (c-object NAME PROP ...)224225Specifies a compiled C/C++ object file. Usually this component type226is required if you want to link a separately compiled C/C++ module227with your extension or program. C-objects are compiled like Scheme228source files with the {{csc}} tool to ensure the same C compiler229options and toolchain is used as for regular Scheme files compiled230to C. If you want to pass compiler-specific options to the build231of the C object, use the {{csc-options}} property and precede232C compiler options with {{-C}}.233234235=== Component properties236237==== host238239 [egg property] (host PROP ...)240241Process {{PROP ...}} recursively for the current component, but242apply the properties only to the host (build) part, when using243a CHICKEN installation intended for cross-compilation.244245==== target246247 [egg property] (target PROP ...)248249Process {{PROP ...}} recursively for the current component, but250apply the properties only to the target part, when using251a CHICKEN installation intended for cross-compilation.252253==== linkage254255 [egg property] (linkage LINKAGE)256257Define whether the component should be linked dynamically or258statically. {{LINKAGE}} can be {{static}} or {{dynamic}}. This259property only makes sense for extension libraries.260261==== types-file262263 [egg property] (types-file [NAME])264265Specifies that a "type-database" file should be generated and266installed for this component. This property is only used for267extension libraries. The name is optional and defaults to the268name of the extensions (with the proper extension).269270If {{NAME}} is a list of the form {{(predefined [NAME])}}, then271no types file is created during compilation and an existing types file272for this extension is assumed and installed.273274==== inline-file275276 [egg property] (inline-file [NAME])277278Specifies that an "inline" file should be generated and installed279for this component. This property is only used for extension280libraries. The name is optional and defaults to the281name of the extensions (with the proper extension).282283==== custom-build284285 [egg property] (custom-build STRING)286287Specifies a custom build operation that should be executed instead of288the default build operations. This property is mandatory for289components of type {{generated-source-file}}. {{STRING}} should be the290name of a shell command (e.g., a script) and thus may be platform291sensitive. The path to the file is prepended implicitly, so you292should '''not''' prefix it with {{./}}. On Windows, a file with the293{{.bat}} extension will be picked before a plain file with no294extension.295296The script will be made executable on UNIX systems, if necessary,297and will be invoked like the {{csc}} program and298is executed with the location of the CHICKEN299binaries in the {{PATH}}. Also, the following environment variables300are set in the execution environment of the script:301302* {{CHICKEN_CC}}: name of the C compiler used for building CHICKEN303* {{CHICKEN_CXX}}: name of the C++ compiler set during the build of CHICKEN304* {{CHICKEN_CSC}}: path to {{csc}}305* {{CHICKEN_CSI}}: path to {{csi}}306307308==== csc-options309310 [egg property] (csc-options OPTION ...)311312Specifies additional compiler options for {{csc}} that should be313used when building this component. If this property is not314given, the default options are used, which are {{-O2 -d1}}315for extensions and programs and {{-O2 -d0}} for import316libraries.317318Note that the options are quoted when passed to csc during the319compilation of the extension, so multiple options should be specified320as {{(csc-options "OPT1" "OPT2" ...)}} instead of {{(csc-options "OPT1 OPT2")}}321(the latter would be a single option containing a whitespace character).322323==== link-options324325 [egg property] (link-options OPTION ...)326327Specifies additional link options for {{csc}} that should be328used when building this component.329330Note that the options are quoted when passed to csc during the331compilation of the extension, so multiple options should be specified332as {{(link-options "OPT1" "OPT2" ...)}} instead of {{(link-options "OPT1 OPT2")}}333(the latter would be a single option containing a whitespace character).334335Note that in order to pass linker options to the underlying C-compiler, these must336be prefixed with {{-L}}, eg. {{(link-options "-L" "-lpng")}}.337338==== source339340 [egg property] (source NAME)341342Specifies an alternative source file, in case it has a name343distinct from the component name. By default the source file344for a component is named after the component, with the {{.scm}}345extension added.346347==== install-name348349 [egg property] (install-name NAME)350351Specifies an alternative installation name of the component,352if it differs from the actual component name. This property353is most useful if an egg installs an extension and a program354of the same name, but needs to distinguish the components during355build time.356357==== component-dependencies358359 [egg property] (component-dependencies NAME ...)360361Specifies dependencies to other components. {{NAME ...}} must362be the names of extension, program, scheme-include- or generated source file363components that should be built before the current component.364365==== source-dependencies366367 [egg property] (source-dependencies NAME ...)368369Specifies dependencies to additional source files. {{NAME ...}} must370denote filenames of which the program or extension depends.371A program or extension implicitly depends on its source file and372and on the egg-specification file.373374==== objects375376 [egg property] (objects NAME ...)377378Specifies that the components of type {{c-object}} should be linked379to this component and that the object components are dependencies.380381382==== destination383384 [egg property] (destination NAME)385386Specifies an alternative installation destination for the387built component and only applies388to components of type {{data}}, {{c-include}} and {{scheme-include}}.389This property should only be used in extreme390cases, as it is recommended to use the default installation391locations, which are:392393* for C include files: {{<PREFIX>/include/chicken/}}394395* for Scheme include files: {{<PREFIX>/share/chicken/}}396397* for data files: {{<PREFIX>/share/chicken/}}398399==== files400401 [egg property] (files NAME ...)402403Specifies source files for this component and only applies404to components of type {{data}}, {{c-include}} and {{scheme-include}}.405Both files and directories may be given and parent directories406are created as needed.407408==== modules409410 [egg property] (modules NAME ...)411412Specifies modules that the component (usually an extension) contains.413{{chicken-install}} will compile and install all import libraries for the given modules.414If this property is not given, then it is assumed that the extension has a single415module of the same name as the component.416417==== cond-expand418419 [egg property] (cond-expand CLAUSE ...)420421Similar to the toplevel {{cond-expand}} clause and may appear inside422component specifications.423424==== error425426 [egg property] (error STRING ARG ...)427428Similar to the toplevel {{error}} form, may appear inside component specifications.429430---431432Previous: [[Extension tools]]433434Next: [[Units and linking model]]